<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>gradientFD :: Functions (k-Wave)</title>
	<link rel="stylesheet" href="kwavehelpstyle.css" type="text/css">
</head>

<body>
<div class="content">

<h1>gradientFD</h1>
<p class="purpose">Calculate the gradient using a finite-difference method.</p>

<h2>Syntax</h2>

<pre class="codeinput">
fx = gradientFD(f, dx)
fx = gradientFD(f, dx, [], deriv_order)
fx = gradientFD(f, dx, [], deriv_order, accuracy_order)
fn = gradientFD(f, dn, dim)
fn = gradientFD(f, dn, dim, deriv_order, accuracy_order)
[fx, fy] = gradientFD(f, dn)
[fx, fy] = gradientFD(f, dn, [], deriv_order, accuracy_order)
[fx, fy, fz, ...] = gradientFD(f, dn)
[fx, fy, fz, ...] = gradientFD(f, dn, [], deriv_order, accuracy_order)
</pre>

<h2>Description</h2>
<p><code>gradientFD</code> calculates the gradient of an n-dimensional input matrix using the finite-difference method. For one-dimensional inputs, the gradient is always computed along the non-singleton dimension. For higher dimensional inputs, the gradient for singleton dimensions is returned as 0. For elements in the centre of the grid, the gradient is computed using centered finite-differences. For elements on the edge of the grid, the gradient is computed using forward or backward finite-differences. The order of accuracy of the finite-difference approximation is controlled by <code>accuracy_order</code> (default = 2). The calculations are done using sparse multiplication, so the input matrix is always cast to double precision.</p>

<p>A 1D example:</p>

<pre class="codeinput">
<span class="comment">% compute gradient of a 2 period sinusoid</span>
x = pi/20:pi/20:4*pi;
y = sin(x);
dydx_4th_ord = gradientFD(y, pi/20, [], 1, 4);

<span class="comment">% plot gradient and error compared to analytical solution</span>
subplot(2, 1, 1), plot(x, cos(x), 'k-', x, dydx_4th_ord, 'bx');
axis tight;
title('dy/dx');
subplot(2, 1, 2), plot(x, cos(x) - dydx_4th_ord, 'k-');
axis tight;
title('Relative Error');
</pre>

<img vspace="5" hspace="5" src="images/gradientFD_01.png" style="width:560px;height:420px;" alt="">

<h2>Inputs</h2>

<table class="body">
    <tr valign="top">
        <td><code>f</code></td>
        <td>matrix or vector to find the gradient of</td>
    </tr>
    <tr valign="top">
        <td width = "150"><code>dn</code></td>
        <td>array of values for the grid point spacing in each dimension. If a value for <code>dim</code> is given, <code>dn</code> is the spacing in dimension <code>dim</code>.</td>
    </tr>
</table>

<h2>Optional Inputs</h2>

<table class="body">
    <tr valign="top">
        <td width = "150"><code>dim</code></td>
        <td>optional input to specify a single dimension over which to compute the gradient for n-dimension input functions</td>
    </tr>
    <tr valign="top">
        <td width = "150"><code>deriv_order</code></td>
        <td>order of the derivative to compute, e.g., use 1 to compute df/dx, 2 to compute df^2/dx^2, etc. (default = 1)</td>
    </tr>
    <tr valign="top">
        <td width = "150"><code>accuracy_order</code></td>
        <td>order of accuracy for the finite difference coefficients. Because centered differences are used, this must be set to an integer multiple of 2 (default = 2)</td>
    </tr>
</table>

<h2>Outputs</h2>

<table class="body">
    <tr valign="top">
        <td width = "150"><code>fx, fy, ...</code></td>
        <td>gradient in the each dimension, where x corresponds to dim = 1, y corresponds to dim = 2 etc.</td>
    </tr>
</table>

<h2>See Also</h2>

<code><a href="getFDMatrix.html">getFDMatrix</a></code>, <code><a href="matlab: doc gradient">gradient</a></code>, <code><a href="gradientSpect.html">gradientSpect</a></code>

</div></body></html>